Skip to main content

Event Gateway

The Event Gateway provides a RESTful API to receive events from external sources. It automatically parses the request body and maps the received data to Actions variables for use in workflow design.

The Event Gateway is preconfigured on your Actions instance and ready to receive events.

Authentication​

All Event Gateway endpoints require authentication.

The username is the Events Client ID of the tenant, and the password is the tenant's Event Secret Key with authentication.

In addition, all request URLs feature the Tenant ID.

Acquiring the Events Client ID​

The Events Client ID is used as the username. To obtain the Events Client ID, follow these steps:

  1. From the top navigation bar, open the hamburger menu and go to Configuration > API Access > Tenant Details.
  2. Take note of the Value field of Events Client ID.

Acquiring the Secret Key​

The Secret Key is used as the password. To obtain the Secret Key, follow these steps:

  1. From the top navigation bar, open the hamburger menu under the Configuration section select API Access.
  2. In the Secret Keys section, click the plus sign at the top right of the list.
    The Secret Keys – New Secret Key sidebar appears. Enter the following information:
    • Name, enter a name that will help you identify the key.
    • Type: select Event
  3. Click Save.
  4. From the Generate Secret Key dialog box that appears, copy and take note of the Value field.
    Caution

    The value is only presented once. If you fail to copy it, you will have to regenerate the key.

  5. Click OK to close the Generate Secret Key window.
  6. To complete the process, click Save near the bottom of the sidebar.

Acquiring the Tenant ID​

The Tenant ID is used as part of the request URL. To obtain the Tenant ID, follow these steps:

  1. From the top navigation bar, open the hamburger menu under the Configuration section select API Access.
  2. Under the Tenant Details section, select the Tenant ID entry.
  3. Within the sidebar, locate and copy the Tenant ID Value.

Acquiring the Event URL​

The Event URL can be acquired from the Support Team or from the Configuration menu. To obtain the Event URL,

  1. From the top navigation bar, open the hamburger menu under the Configuration section and select API Access.
  2. Under the Tenant Details section, find the eventClientUrl entry.
  3. Copy the the value.

Sending an Event to the Event Gateway​

Use an authenticated POST request to send events to Actions.

HTTP Method​

POST

Request URL​

Send requests to the following URL:

https://actions-api-prod.resolve.io/api/Webhooks/postEvent/<Tenant ID>

Where:

Request Authentication​

Basic authentication is required. See Headers.

Request Headers​

The following request headers are required:

  • Content-Type—Indicates the media type of the body. Supported values:
    • application/json
    • application/xml
    • text/plain
  • Authorization—Basic authentication is required. See Authentication to learn how to set up a username and a password.
Body Format​

Requests can be sent in the following formats:

  • XML (text/xml)
  • JSON
  • String
Response​

The Event Gateway replies with one of the status codes listed below.

Status CodeMessageDescription
200SuccessMessage was sent successfully.
401UnauthorizedIndicates an issue with the credentials
403ForbiddenThe source IP is not included in the allowed IP range.
Examples​

In the following example, we pass three custom parameters (eventDetail1, eventDetail2, eventDetail3).

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <eventDetail1>Event Gateway detail 1</eventDetail1>
    <eventDetail2>Event Gateway detail 1</eventDetail2>
    <eventDetail3>Event Gateway detail 1</eventDetail3>
</root>

The returned response is OK (status code 200 - Success).

Viewing Incoming Requests​

Incoming requests can be viewed from the Main Menu under Insight > Audit Trail.

To see details about a specific event, click in its row in the Audit Trail. The details will be displayed in the Activity Log panel below.

To see details about a returned message, click the green arrows in the desired row of the Message column. This is an example of how they will look:

Each request parameter is displayed as a row in the Key column. It is automatically mapped as a variable that you can use to access the parameter's value in workflows—for example: %eventDetail1%, %eventDetail2%, %eventDetail3%.

Each event includes the following details:

  • The parameters sent. In our example, this is %eventDetail1%, %eventDetail2%, %eventDetail3%.
  • RawData: The raw request body.
note

Using %body% as a variable in a workflow will return the entire row data.

Automating an Incoming Event​

Sending a request to the Event Gateway generates an event in Actions, visible in the Audit Trail. To automate the event, you need to create a trigger for a workflow.

Triggers for the Event Gateway work by matching a global variable with the data received in the event. If you want to react to multiple values of the same parameter, repeat the following procedure for each of them, creating separate global variables.

Take these steps to automate the event coming in from the Event gateway:

  1. Create a global variable that matches the data that you expect to receive from the external source:
    • For Name, enter the exact name of a parameter received as part of the incoming request's body.
      Matching a single body parameter is enough to trigger an automation.
    • For Mode, select Set Variable's Value on Every Incident Update.
    • Type cannot be set in this use case.
    • Leave Value empty.
  2. Create the Workflow that will automate the event if it doesn't already exist.
    You can create a non-functioning workflow and build it later.
  3. Create a trigger for a workflow:
    1. When prompted to create a Condition, configure it as follows:
    • Set Condition Clause to any value. It is irrelevant as the condition only requires a single condition entry.
    • Under Condition Logic, add an entry as follows:
      • Type—Global Variables.
      • Module Form—Cannot be set in this use case.
      • Object—Select the global variable that you created for this automation.
      • Operator—Equals.
      • Value—The exact value of the parameter from the request's body that matches the global variable.
    1. When prompted to create a Trigger, configure it as follows:
      • Ensure that Enabled is checked.
        You might want to leave it unchecked if you are yet to build the workflow.
      • Under Conditions, create an entry as follows:
        • Condition—Select the condition that you created for this event.
        • Workflow—Select the workflow that you created for this event.
        • Optionally, set the rest of the options as needed.

The selected workflow will execute the next time that the Event Gateway receives the parameter and value combination that you specified.